home *** CD-ROM | disk | FTP | other *** search
/ Softdisk G-S 128 / SGDS 128.2mg / SDGS.128 / SDC128 / C / APE.DOC#040000 < prev    next >
Text File  |  1992-07-25  |  45KB  |  937 lines
  1.  
  2.                           Apple Program Environment
  3.                                        
  4.                                Douglas B. Eamon
  5.                            Department of Psychology
  6.                      University of Wisconsin - Whitewater
  7.                             Whitewater, WI  53190
  8.  
  9.  
  10.      The "desktop metaphor," including pulldown menus and windows described in
  11. Apple's Human Interface Guidelines, has become a preferred, if not standard,
  12. program environment for many applications.  While commonly seen on the Apple
  13. IIgs, Mac, and IBM, they have remained largely unused by Applesoft programmers
  14. on the IIe and IIc, primarily because of the difficulty in implementing them
  15. from that language. 
  16.  
  17.      This file describes a simple yet powerful menu/window programming
  18. environment for Applesoft users.  The program functions in 80-column text mode
  19. only.  It will work on any of the Apple II family which supports mouse
  20. characters, including the Apple IIgs (although it does not use the IIgs's
  21. toolbox menu and window functions), IIc, or enhanced IIe.  With some revision,
  22. it could also work on an unenhanced IIe or even a II+, provided the user is
  23. willing to substitute other characters for mouse characters used as frames for
  24. the menus and windows. 
  25.  
  26.      The assembly language program which provides these functions is called
  27. Apple Program Environment, or APE.  In addition to allowing pulldown menus
  28. and multiple windows, APE includes a command interpreter, a text printing
  29. utility, and an "input anything" utility.  The command interpreter allows the
  30. program user to select an option without using the pulldown menus, for
  31. example, by pressing the open-Apple key along with a keyboard character.  The
  32. text printing utility prints text within the currently defined window with
  33. word wrapping. 
  34.  
  35.      APE is easy to use, flexible, and compact.  An Applesoft program using
  36. APE can allow the program user to use the arrow keys to select an option
  37. from a menu bar or a pulldown menu, get a command from the keyboard, open or
  38. close a window, or print text within a window. APE executes the function
  39. and returns any appropriate values (e.g., the menu item selected) to
  40. Applesoft. 
  41.      The general form of a command to APE is
  42.  
  43. CMND, parm1, parm2, ..., parmN     where
  44.  
  45. CMND is the command you want to execute and parm1, parm2, etc., are values
  46. used by APE  (e.g., menu items, screen locations for a window to be
  47. opened). 
  48.  
  49. The commands and their functions are as follows:
  50.  
  51.    Command    Function
  52.       M       Print a menu and allow the user to select
  53.               a menu option or input a keyboard command
  54.      GET      Present an input prompt and get the user's 
  55.               selection of a keyboard command; accept only 
  56.               keys passed to the routine
  57.      WBP      Clear a screen window area and save the screen
  58.               contents in a string array using the "packed"
  59.               format; make a window with borders and print a
  60.               title (if given) centered in the top border
  61.      WBU      Same as WBP, except save in unpacked format
  62.      WNP      Clear window area and save screen in packed
  63.               format, but do not print border or title
  64.      WNU      As above, but use unpacked format
  65.      WSP      Save screen to array in packed format, but
  66.               do not clear screen, draw border or print title
  67.      WSU      As above, unpacked format
  68.      WRD      Remove a window by restoring the contents of the
  69.               screen to their previous state, then delete the 
  70.               storage array from memory
  71.      WRK      Remove a window and restore screen, but do not 
  72.               delete the storage array from memory
  73.     PRINT     Print text in currenty defined window with
  74.               word wrapping
  75.     INPUT     Input a line which might include commas, quotes,
  76.               etc.
  77.     CLEAR     Clear the screen with the character(s) passed to
  78.               the routine.
  79.  
  80.  
  81.      APE may be implemented using either the ampersand (&) command, or the
  82. CALL address command if the ampersand command is already in use.  For
  83. simplicity, I assume that the ampersand is being used.  APE is
  84. compatible with both DOS 3.3 and ProDOS.  It is 2455 bytes long. 
  85.  
  86.                                     Menus
  87.  
  88.      APE's pulldown menu is "traditional"-looking and appears much like
  89. those found on the Mac and Apple IIgs, except that it is entirely text-based
  90. (although it will display mouse characters).  A "menu bar" in inverse video is
  91. shown at the top of the screen in which the current item is highlighted by
  92. printing it in normal video.  The pulldown menus are presented by pressing
  93. <RETURN> or the down arrow key; pulldown item selections are displayed in
  94. normal video, except the current item, which is highlighted in inverse video.
  95. The pulldown items are presented in a frame aligned with the left edge of the
  96. menu bar selection.  The current item (whether in the main menu or a pulldown
  97. menu) can also be made to blink (not flash) on and off at a preselected
  98. speed. 
  99.  
  100.  
  101.      The command syntax used to display a menu and obtain the user selection
  102. is: 
  103.  
  104. & M, MAIN, SUB, ME$(0) [,BS]              where
  105.  
  106.      The "M" instructs APE to perform the menu function; MAIN, SUB, and
  107. ME$(0), are user-defined variables, and BS is a user-defined variable or
  108. constant.  M may be a variable in your program, but is not interpreted as such
  109. by APE, and its value will not be altered by APE. 
  110.  
  111.      MAIN is the main (menu bar) selection.  If MAIN = 0, the menu bar will be
  112. printed (with no items highlighted), and the routine will immediately return.
  113. This is useful if you just want to print the menu bar and go on to do other
  114. things; the menu bar provides a reference frame for the rest of the program.
  115. If MAIN > 0, the corresponding menu bar item will be highlighted.  When the
  116. user makes a selection from the menu bar, MAIN is used to return the selection
  117. to the program. 
  118.  
  119.  
  120.  
  121.      SUB is the submenu (pulldown menu) selection.  If MAIN > 0 and SUB > 0,
  122. the submenu items will be displayed in a pulldown menu with item SUB
  123. highlighted (displayed in inverse video, blinking), and the program will wait
  124. for user input.  If SUB = 0, the submenu will not be pulled down.  SUB is also
  125. used to return the users selection of the pulldown item. 
  126.  
  127.      ME$(0) is a string array which contains the menu items in elements 1 - n,
  128. where n is the number of main menu items.  Element 0 of the array may contain
  129. keyboard commands to be interpreted by APE.  These may be alternative ways
  130. of selecting menu items or entirely different commands.  Keyboard commands are
  131. discussed below under "Command Interpreter."
  132.  
  133.      BS is an optional variable which controls the "blinking speed," or rate
  134. at which the menu items will blink on and off while the program waits for user
  135. input.  Larger values create longer delays between blinks.  To prevent
  136. blinking, set this value to 0, or leave it out of the list of parameters. 
  137.  
  138.  
  139.  
  140.  
  141.      When the user makes a selection from the menu, the pulldown menu is
  142. closed, MAIN and SUB are reset to the new selection and the routine returns to
  143. Applesoft.  The program user makes his or her selection from the main menu
  144. level by moving the arrow keys left or right; to display the associated
  145. pulldown menu, the user can press either RETURN or the down arrow.  If there
  146. are no pulldown items the down arrow is ignored; a RETURN causes the main item
  147. to be selected, and APE returns with its value to the calling Applesoft
  148. program.  If pulldown items are defined, the user can move up and down the
  149. pulldown menu using the up and down arrows; pressing RETURN selects the item
  150. and APE returns the value of the main menu item and the pulldown item to
  151. the calling program.  If the user presses a left or right arrow while on a
  152. pulldown item, the pulldown menu is closed and the next main menu item is
  153. highlighted. 
  154.  
  155.      If the user presses an acceptable keyboard command (see the information
  156. on the Command Interpreter, below) while the menu command is active, any
  157. pulldown menus are closed, MAIN is set to 0 and SUB is set to the the number
  158. of the command. 
  159.  
  160.  
  161. Defining a menu
  162.  
  163.      In order to use APE's menu routine, you need to define a set of menu
  164. i